home *** CD-ROM | disk | FTP | other *** search
/ EnigmA Amiga Run 1995 October / EnigmA AMIGA RUN 01 (1995)(G.R. Edizioni)(IT)[!][issue 1995-10][Aminet 7].iso / Aminet / comm / xeno / topper.lha / Topper / Topper.doc < prev   
Text File  |  1995-04-01  |  12KB  |  386 lines
  1.  
  2.  
  3.                      TOPPER v1.1 by Henri Veisterä
  4.                      =============================
  5.  
  6.       - A Freely Customizable Top X Bulletin Creator For Xenolink
  7.  
  8.  
  9.  
  10. Document Index:
  11. ===============
  12.  
  13.  
  14. 1.  Updating from version 1.0
  15. 2.  Version history
  16. 3.  Quick example
  17. 4.  Usage
  18. 5.  Installing
  19. 6.  Output
  20. 7.  Customizing
  21. 8.  Unwanted users
  22. 9.  Extra mush
  23. 10. The End
  24.  
  25.  
  26.  
  27. 1.  Updating from version 1.0
  28. =============================
  29.  
  30.  
  31. If you already have Topper running on your system, do this:
  32.  
  33. 1. Read the section 2. Version history for update info.
  34. 2. Make  a  directory  XENOLINK:Text/Topper.   Move  your Topper form files
  35.    (XTEXT:T*F*.*),  XENOLINK:Ratings.txt  and  XENOLINK:NoTopper.txt  files
  36.    here.
  37. 3. New  default  output  directories  are  XENOLINK:Text/0/  for  ascii and
  38.    XENOLINK:Text/1/  for  ansi.   Both ansi and ascii versions now have the
  39.    same  name  without  the suffix (.txt or .gr1) so you can't use the same
  40.    directory for both.  You can change the directories with the -o1 and -o2
  41.    command line options.
  42. 4. Edit your Ratings.txt file and change all the ":" in ratios to "~".
  43.    "1:3" -> "1~3"
  44. 5. Copy the new executable over your old one.
  45.  
  46.  
  47.  
  48. 2.  Version history
  49. ===================
  50.  
  51.  
  52. Version 1.1 - released 01-Apr-1995
  53. ----------------------------------
  54.  
  55. Fixed   a   bug   where   Topper   could   crash   if   there   were  no
  56. Uploads/Downloads/Messages/Calls  recorded  in  the user file for any of
  57. the users (ie.  zero users to display in the charts).
  58.  
  59. If user had more than 1,4 Giga Bytes of uploads/downloads/etc.  this was
  60. not  displayed  correctly.   Now  displays correctly upto Xenolink's own
  61. maximum of 2,4 GB.
  62.  
  63. Changed the default paths so that Topper no longer needs the obsolete Z3
  64. version  assigns  (XUSERS:   XTEXT:  XBULLETINS:).  All Topper files can
  65. now be found in the XENOLINK:Text/Topper/ directory.
  66.  
  67. Topper  now  has different output dirs for ansi and ascii versions.  The
  68. default  path  for  ascii  texts  is XENOLINK:Text/0/ and for ansi texts
  69. XENOLINK:Text/1/.  There is no -o option anymore, this was replaced with
  70. the -o1 and -o2 options.
  71.  
  72. Added the ~P tilde code to display users alias.
  73.  
  74. Added the ~Z tilde code to display users download bytes divided by their
  75. upload  bytes or vice versa with one decimal point accuracy.  A plus (+)
  76. sign  is  added  if user has more uploads than downloads and a minus (-)
  77. sign is added if user has more downloads than uploads.
  78.  
  79. Added the -k option for a double row display (two users per line).
  80.  
  81. Added  the  -j  command line option to specify the character to separate
  82. three digit groups in numbers displayed (default is "'" : 9'999'999).
  83.  
  84. Changed the ratio separator in Ratings.txt from ":" to "~" so that
  85. you can use ":" in your ratings.
  86.  
  87.  
  88. Version 1.0 - released 16-Dec-1992
  89. ----------------------------------
  90.  
  91. First public release.
  92.  
  93.  
  94.  
  95. 3.  Quick example
  96. =================
  97.  
  98.  
  99. To  quickly  try  out  Topper try this in CLI in the directory where you
  100. unpacked the Topper archive (in this example to ram:)
  101.  
  102. MakeDir ram:0 ram:1
  103.  
  104. Topper -a -b -c -d -e -f -g1 -r -iram:Topper/Forms1/ -o1ram:0/ -o2ram:1/
  105.  
  106. Type ram:0/Topper#?
  107. Type ram:1/Topper#?
  108.  
  109. Topper -a -b -c -d -e -f -g1 -iram:Topper/Forms2/ -o1ram:0/ -o2ram:1/
  110.  
  111. Type ram:0/Topper#?
  112. Type ram:1/Topper#?
  113.  
  114. Topper -a -b -c -d -e -f -g1 -k -r -20 -iram:Topper/Forms3/ -o1ram:0/ -o2ram:1/
  115.  
  116. Type ram:0/Topper#?
  117. Type ram:1/Topper#?
  118.  
  119.  
  120.  
  121. 4. Usage
  122. ========
  123.  
  124.  
  125. Topper  can  be  run  from  the  CLI or from a script.  The command line
  126. syntax is as follows:
  127.  
  128. Topper -<operation> -[options]
  129.  
  130. Where <operation> is one or more of:
  131.  
  132.  -a     - create two charts (ansi&ascii) sorting users by their upload bytes
  133.  -b     - create two charts sorting users by their download bytes
  134.  -c     - create two charts sorting users by their uploaded files
  135.  -d     - create two charts sorting users by their downloaded files
  136.  -e     - create two charts sorting users by their calls to bbs
  137.  -f     - create two charts sorting users by their written messages
  138.  -g     - create two charts sorting files by their access count
  139.  
  140.  -g option format is: -gfilebase1,filebase2,filebase3... 
  141.  
  142.  
  143. And [options] is one or more of:
  144.  
  145.  -i     - input path for the form files
  146.  -o1    - output path for the ascii output files
  147.  -o2    - output path for the ansi output files
  148.  -xx    - the number of users/files to include in the chart
  149.           ranging from 1-9999, default is 10
  150.  -j     - three digit group separator, default is "'" (ex. 9'999'999)
  151.  -r     - copyright message at the end of the output, no
  152.           screen clearing code at the beginning of output, plan
  153.           for this in your form files
  154.  -k     - display two users per row
  155.  
  156. The paths (-i -o1 -o2) must have a trailing slash (/) or colon (:). 
  157.  
  158. The options are not case sensitive and can be in any order.
  159.  
  160. Example command lines:
  161.  
  162. Topper -f -e -20
  163.  
  164.  - Create caller and message charts for the 20 best users.
  165.  
  166. Topper -g20,1 -a -b -15 -o1ram:0/ -o2ram:1/ -ixtext:myforms/ -r
  167.  
  168.  - Create most downloaded file charts from files in filebases 20 and 1
  169.   and upload and download bytes charts for the 15 best users and files.
  170.   Output files are created in ram:  and the form files are fetched from
  171.   the xtext:myforms/ directory.  The copyright message is inserted at
  172.   the end of the output.
  173.  
  174. Topper -a -b -c -d -e -f -g1,2 -j,
  175.  
  176.  - Create all possible charts for the 10 (default) best users/files.
  177.    Output and input paths are the default ones.
  178.    The numbers displayed look like this: 1,234,567,890 .
  179.  
  180.  
  181.  
  182. 5.  Installing
  183. ==============
  184.  
  185.  
  186. First  copy  the executable file 'Topper' to your c:  directory.  Make a
  187. directory  with the name XENOLINK:Text/Topper.  Copy the T*F*.* files to
  188. your   XENOLINK:Text/Topper/   directory.   Copy  the  NoTopper.txt  and
  189. Ratings.txt to your XENOLINK:Text/Topper/ directory.
  190.  
  191. Or use the installation script provided.
  192.  
  193. Normally  this  kind  of  a  utility  would  be  run  from your logout.X
  194. script(s).   To  do  this  add  this  or  a similar command line to your
  195. script(s):
  196.  
  197. Topper -a -b -c -d -e -f -g1,2,3,4,5 -r
  198.  
  199. Alternatively you can update the charts every time a users wants to view
  200. them.
  201.  
  202. You can use the TypeFile command in Xenolink to display your charts.
  203.  
  204.  
  205.  
  206. 6.  Output
  207. ==========
  208.  
  209.  
  210. Topper's  default  output  directories  are  your  XENOLINK:Text/0/  and
  211. XENOLINK:Text/1/  directory.   Specify  a different output path with the
  212. -o1 and -o2 options.
  213.  
  214. The fixed names for the charts are:
  215.  
  216.  TopperUl     - top uploaders (bytes)
  217.  
  218.  TopperDl     - top downloaders (bytes)
  219.  
  220.  TopperUl2    - top uploaders (files)
  221.  
  222.  TopperDl2    - top downloaders (files)
  223.  
  224.  TopperCalls  - top callers
  225.  
  226.  TopperMsgs   - top message writters
  227.  
  228.  TopperFile   - top downloaded files
  229.  
  230.  
  231.  
  232. 7.  Customizing
  233. ===============
  234.  
  235.  
  236. Output  is  customized  with 10 different T*F.* files.  The default path
  237. for  these files is your XENOLINK:Text/Topper/ directory.  Specify a new
  238. path  with  the  -i  command  line option.  The tilde (~) codes in these
  239. files  are replaced with the relevant information and a copyright notice
  240. is  added  either  to  the top or to the bottom of the output files (see
  241. option -r).
  242.  
  243. You  can  edit  these  files  as  much as you want to with a common text
  244. editor.
  245.  
  246. The  first  line  starting  with two @-chars is copied for every user or
  247. file  listed  and  the  tilde codes are again replaced with the relevant
  248. information.
  249.  
  250. The  actual  difference  with the .gr1 and .txt files is that you get an
  251. ansi  copyright  line  for  the .gr1 files and an ascii one for the .txt
  252. files.   Your .txt files can of course contain ansi-sequences or control
  253. codes if you so wish (and vice versa).
  254.  
  255. The tilde codes are:
  256.  
  257.  - @@ line codes for users (strings or 32 bit integers)
  258.  
  259.  ~A   - a running number starting from 1 increased for every user by 1
  260.  ~B   - current users name
  261.  ~P   - current users alias
  262.  ~C   - users location
  263.  ~D   - users uploaded bytes
  264.  ~E   - users downloaded bytes
  265.  ~S   - users uploaded kilos
  266.  ~T   - users downloaded kilos
  267.  ~F   - uploaded files
  268.  ~G   - downloaded files
  269.  ~H   - number of calls
  270.  ~I   - number of messages
  271.  ~V   - users rating (length defined in Ratings.txt)
  272.  ~W   - download:upload ratio "1:123" (fixed length is 5, always use: ~WWWW)
  273.  ~Z   - dl/ul ratio "-27.3" or ul/dl ratio "+ 2.6" (always use: ~ZZZZ)
  274.  
  275.  - @@ line codes for files (strings or 32 bit integers)
  276.  
  277.  ~a   - filename
  278.  ~b   - files uploader
  279.  ~c   - files section
  280.  ~d   - files length
  281.  ~e   - access count
  282.  ~f   - date uploaded (fixed length is 9, always use: ~ffffffff)
  283.  ~g   - date last downloaded (fixed length is 9, always use: ~gggggggg)
  284.  
  285.  - tilde codes to place anywhere (strings or 64 bit integers)
  286.  
  287.  ~J   - total number of bytes uploaded to the bbs
  288.  ~K   - total number of bytes downloaded
  289.  ~L   - total files uploaded
  290.  ~M   - total files downloaded
  291.  ~N   - total calls to bbs
  292.  ~O   - total messages written by all the users
  293.  ~Q   - total uploads in mega bytes
  294.  ~R   - total downloads in mega bytes
  295.  ~X   - total uploads in kilo bytes
  296.  ~Y   - total downloads in kilo bytes
  297.  ~U   - total number of users
  298.  
  299. You control the space taken up by these codes like this:
  300.  
  301. ~BBBBBBBBBBBBBBBB - Displays the first 17 chars of the users name.
  302.  
  303. Another thing you can customize are the ratings you can give to users by
  304. their  upload  to  download ratios.  These ratings are defined in a file
  305. called XENOLINK:Text/Topper/Ratings.txt .  The format of the file is :
  306.  
  307. ...
  308. 1~RATIO,RATING
  309. 1~1,RATING
  310. RATIO~1,RATING
  311. ...
  312.  
  313. The  1~RATIO's  are  for  those  people  who have more upload bytes than
  314. download  bytes.  And the RATIO~1's are for those who have more download
  315. bytes  than  upload  bytes.  You can have one 1~1 ratio rating for those
  316. who have approx.  the same amount of uploads and downloads.
  317.  
  318. An example: You have these ratings defined:
  319.  
  320. 1~3,Best!
  321. 1~2,Good!
  322. 1~1,  -  
  323. 2~1,Bad!!
  324.  
  325. An  user  with  1024'1234 upload bytes and 512'0617 download bytes has a
  326. ratio  of  1~1024'1234/512'0617 = 1~2.  His rating would be 'Good!'.  An
  327. user  with  1024'1234  upload bytes and 512 download bytes would get the
  328. rating  'Best!'  altough  his actual ratio is much larger.  An user with
  329. 345'434  upload  bytes and 1'234'321 download bytes would get the rating
  330. 'Bad!!'  and  so  on.   All  users whose ratios are in the 1~1.4 - 1.4~1
  331. range get the 1~1 rating ' - '.
  332.  
  333. Be  careful to check that all your ratings are of equal length.  If some
  334. are shorter than the others, pad them with extra spaces or other chars.
  335.  
  336. Do not use the tilde ~ char in your ratings texts.
  337.  
  338.  
  339.  
  340. 8.  Unwanted users
  341. ==================
  342.  
  343.  
  344. If  you  have  users  (like yourself and your aliases) you don't want to
  345. have   in   the   charts,   list   their   names   in   a   file  called
  346. XENOLINK:Text/Topper/NoTopper.txt.   End every name with a return (ascii
  347. code 10).  The names are not case sensitive.  See example in archive.
  348.  
  349.  
  350.  
  351. 9.  Extra mush
  352. ==============
  353.  
  354.  
  355. If for some reason you want different NoTopper.txt files for your charts
  356. do this:
  357.  
  358. Make  many  NoTopper  files  and  name  them something like NoTopper.1 ,
  359. NoTopper.2 ...  .  Use a logout.X script like this:
  360.  
  361. ...
  362. cd XENOLINK:Text/Topper
  363. copy NoTopper.1 NoTopper.txt
  364. Topper -a -10
  365. copy NoTopper.2 NoTopper.txt
  366. Topper -b -10
  367. ...
  368. copy NoTopper.6 NoTopper.txt
  369. Topper -f -10
  370. ...
  371.  
  372.  
  373.  
  374. 10. The End
  375. ===========
  376.  
  377.  
  378. Topper was coded in 100% assembler by me, Henri Veisterä.
  379.  
  380. To  contact  me leave a message to 'Henri Veistera' in the xenolink.util
  381. net-area or e-mail me at hveister@snakemail.hut.fi .
  382.  
  383. Topper has been tested under many different Amiga/Xenolink setups but if
  384. for some reason it wipes out your hard drive, I'm not responsible.
  385.  
  386.